Cream of the Crop 26/Cream of the Crop 26.iso/bbs/kdom221.zip/KDOC-TXT.ZIP/KSYSOP.TXT

Text File | 1997-06-15 | 50KB | 1,068 lines

        ┌──────────────────────────────────────────────────────┐
        │                       KINGDOMS                       │
        ├──────────────────────────────────────────────────────┤
        │             SYSTEM OPERATOR DOCUMENTATION            │
        │                     Version 2.21                     │
        ├──────────────────────────────────────────────────────┤
        │                                                      │
        │  Programming & Design : Dave Chapman : The Web BBS   │
        │                                                      │
        │   Copyright c 1993, 94, 95, 96, 97 - Dave Chapman    │
        │                 All Rights Reserved                  │
        │                                                      │
        │       3:712/523@FidoNet  169:3005/2@BattleNet        │
        │                                                      │
        ├──────────────── [e-mail] ────────────────┤
        │                                                      │
        │              - Kingdoms Support Page -               │
        │        http://www1.tpgi.com.au/users/kingdoms        │
        │                                                      │
        └──────────────────────────────────────────────────────┘


                           TABLE OF CONTENTS
                           ─────────────────

SECTION 1 - KINGDOMS LICENSING INFORMATION

        1.1. Software License Agreement
        1.2. Definitions
        1.3. Terms
        1.4. Limited Warranty
        1.5. Technical Support
        1.6. Problem Reporting
        1.7. Upgrades

SECTION 2 - GAME OVERVIEW

SECTION 3 - KINGDOMS FILES

        3.1 Executable Files
                3.1.1. KINGDOM.EXE
                3.1.2. KM.EXE
                3.1.3. KNETIN.EXE
                3.1.4. KNETOUT.EXE
                3.1.5. KMNT.EXE
        3.2 Data Files
                3.2.1. KIDX.DAT
                3.2.2. KGAME.DAT
                3.2.3. K*.KDI
        3.3. Generated Files
                3.3.1. KMSGHEAD.DAT & KMSGTXT.DAT
                3.3.2. KUSR.DAT
                3.3.3. KCFG.DAT
                3.3.4. KTRANSIT.DAT
                3.3.5. KSCORE?.KDI
                3.3.6. K?.LOG

SECTION 4 - REQUIRED SOFTWARE/KINGDOMS ENVIRONMENT

SECTION 5 - INSTALLATION

        5.1. Overview
        5.2 Installation Step 1 - The Basics
                5.2.1. Unpack the Archive
                5.2.2. Setting up your Configuration File
        5.3 Installation Step 2 - Network Configuration
                5.3.1. The KIDX.DAT File
                5.3.2. Network Setup
        5.4. Installation Step 3 - Getting it Running
                5.4.1. Logging on Locally
                5.4.2. Starting Kingdoms
                5.4.3.  Maintenance, Network Tasks
        5.5. Installation Step 4 - Multiline Configuration

SECTION 6 - MAINTENANCE OPTIONS
        6.1. Game Reset
        6.2. Override Reset
        6.3. Delay Processing
        6.4. Same-Day Run Override
        6.5. Create ACS/ANS Files
        6.6. Create Scoreboards

SECTION 7 - REGISTRATION

SECTION 8 - CONTACT INFORMATION

SECTION 9 - FAQ
        9.1. Where do I specify my locked port?
        9.2. Kingdoms thinks someone is online when there isn't.
        9.3. Kingdoms thinks Maintenance is running when it isn't.
        9.4. I have an Index file, but the Manager is telling me I don't!
        9.5. Realms on my Index are numbered differently to my uplink!
        9.6. I want to be able to generate Scoreboards anytime!

APPENDIX A : ERROR CODES

APPENDIX B : QUICKSTART INSTALLATION

APPENDIX C : UPGRADING FROM PRIOR RELEASES



Section 1 - Kingdoms Licensing Information

This Software is Licensed, not sold. The Software in this package is
licensed according to the terms of the following agreement: 1.1.

Software License Agreement

IMPORTANT: Please read this license agreement before using this
software. By using this software you acknowledge your agreement to the
terms of this license. If you do not wish to follow the terms of this
license agreement, you must remove this software from your system.  The
only portion of the Software that you may retain is the distribution
archive itself which may be used solely for distribution purposes.

1.2. Definitions

The term "Software" as used in this agreement means the full system and
all utility computer programs contained in the distribution archive,
together with any updates subsequently supplied by DM BBS Services. The
term "Related Materials" means all the printed materials provided in
this package or later supplied by Dave Chapman for use with the
Software. The "Author" as used in this document is Dave Chapman who owns
and holds copyright to the Kingdoms software.

1.3. Terms

You are granted a limited license to use this software for a thirty day
trial period.  After expiration of the trial period, you must either
register with the Author or remove the Software from your system. Single
registrations are A$30.00 (thirty Australian dollars). Generous group
discounts are available and described on the Registration Form
(KREG.DOC, or KREG.TXT) which is included in the distribution archive.
Once registered, you will receive a license to use the Software on your
system for an unlimited period of time. Additional payments may be
required for major game upgrades in future at the discretion of the
Author. Kingdoms is Copyright 1993-97 by Dave Chapman. All rights are
reserved.  You may copy the Software and documentation for backup
purposes.  You also may copy and share unmodified copies of the
distribution archive, providing that the copyright notice is reproduced
and included on all copies and no fee is charged for distributing the
distribution archive.

You may not sell this software for a fee and/or distribute this software
along with other products without expressed written permission from the
Author, nor may you modify or remove the Copyright Notice from the
program or the documentation.

Those who register this program, will receive a registration number.
This number will be delivered either by Internet mail, personal upload,
or postal service. Allow up to 3 weeks for delivery for locations
outside Australia. For locations within the Australia, allow 1-2 weeks
for delivery. All registrations are processed in a timely manner and
usually only take a few days to deliver.  However, when unforseen
circumstances arise, registration turnaround times may be delayed. Your
registration number may not be used on any system other than the one to
which it is registered in any circumstances without written permission
from the Author. The Author reserves to right to revoke software
licenses in lieu of any violation of the terms of this license
agreement.

1.4. Limited Warranty

THIS PRODUCT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  THE
ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE PROGRAM IS ASSUMED
BY YOU. THE AUTHOR DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
REPRESENTATIONS REGARDING THE USE OF, RESULTS OF, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR USE OF THE PRODUCT.  SHOULD THE PROGRAM PROVE
DEFECTIVE, YOU (AND NOT THE AUTHOR) ASSUME THE ENTIRE COST OF ALL
NECESSARY SERVICING, REPAIR OR CORRECTION. FURTHER, THE AUTHOR DOES NOT
WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR
THE RESULTS OF THE USE OF THE PROGRAM IN TERMS OF CORRECTNESS, ACCURACY,
RELIABILITY, CURRENTNESS, OR OTHERWISE; AND YOU RELY ON THE PROGRAM AND
RESULTS SOLELY AT YOUR OWN RISK. THE AUTHOR WILL NOT BE LIABLE FOR ANY
DAMAGES, INCLUDING BUT NOT LIMITED TO SYSTEM DAMAGE, SERVICE, REPAIR,
CORRECTION, LOSS OF PROFIT, LOST SAVINGS, OR ANY OTHER INCIDENTAL,
CONSEQUENTIAL, OR SPECIAL DAMAGES OF ANY NATURE WHATSOEVER RESULTING
FROM THE USE OR INABILITY TO USE THIS PRODUCT.

1.5. Technical Support

Comments, suggestions and bug reports are welcome. If you have any, you
should contact Dave Chapman at one of the addresses listed below:

Primary Support Site:     : The Web BBS
System Operator:           : Dave Chapman
Mailer/BBS Software:         : Maindoor/EzyCom

Line 1            : [phone] to 33600, Continuous Mail, FREQ
Line 2            : [phone] to 28800, BBS - 24 hours
Line 3            : [phone] to 14400, BBS - 24 hours

Sysops can FREQ magic name `KINGDOMS' anytime for the latest version on
line 1. I can be contacted on the Battlenet Kingdoms echo by name or by
Internet mail to [e-mail]. Kingdoms is also available from
the Australian, US, Canadian and New Zealand Beta/Registration sites and
Internet FTP site as listed in Section 8 - Contact Information, in this
document.

1.6. Problem Reporting

If you're reporting a bug, please give as much detail as possible about
the problem you are experiencing (including the version you're running)
so that it can be duplicated and fixed. Please include the error report
that will be provided in KERR.LOG and a screen dump of where the problem
occured if possible.

1.7. Upgrades

Program updates consist of minor and major revisions.  All minor updates
are available for download and usage free of charge to registered
Sysops.  Major updates may require a small upgrade fee based on the
complexity of the update.

The program version number indicates whether this a major or a minor
upgrade.  For example, release revisions 1.10, 1.43, 1.90 etc would
indicate minor program revisions and no upgrade fee would be charged to
those who are currently registered 1.00 users. A release revision of
2.00 would indicate a major program revision and may require a small
upgrade fee.



Section 2 - Game Overview

Kingdoms is a multi user online game with InterBBS capability. It will
run under all BBS systems that support the standard DORINFO1.DEF,
DORINFOx.DEF or DOOR.SYS drop file formats, or for which these file can
be generated.

Other games have purported to be InterBBS, but they merely offer the
user the ability to play on one BBS and send forays to others which must
return to their home BBS. This is really just an extension of a local
BBS game and does not offer true Inter-BBS functionality. Kingdoms does.
:-) Under Kingdoms, players have a `Home' BBS, which is the one they
logon to most frequently. On that BBS, they own a Castle which can be
fortified in a number of ways, they can attack other players either on
the local BBS or on another, send messages between them, etc. As far as
Inter-BBS goes it's all good fun, there is nothing really new here.

What is new, and what makes Kingdoms truly unique is that players in
Kingdoms can purchase castles on other BBS's in their net. They can hire
an `Agent' to run the castle for them, fortify that castle, store gold
in it, send attacks from it and much more, all by remote command from
their Home BBS. If they have created a remote castle, they can also
directly logon to the remote and they will be recognised as a `Visiting
Lord' (or Lady!), owner of the castle there and operate it directly. The
possibilities for strategic play, multiple alliances and subterfuge here
are enormous. It is not the purpose of this document to discuss the game
itself in depth, so if you would like to know more, please read the
Player documentation.

I hope you and your users enjoy the game!


Section 3 - Kingdoms Files

The following files should be in your Kingdoms Archive and are required
to operate Kingdoms on your BBS. If any are missing, the latest version
and archive can be FREQ'd from the Web BBS at the addresses provided in
the Support section of this documentation. 3.1 Executable Files

3.1.1. KINGDOM.EXE

This program is the one that is executed when shelling from a BBS or in
local mode by using the /L command line parameter.

3.1.2. KM.EXE

This is the Kingdoms Manager. When you've unpacked your Kingdoms
archive, this should be the first program you run. A full description of
KM.EXE is provided in the accompanying document, KM.DOC.

3.1.3. KNETIN.EXE

KNetIn processes Kingdom inbound files from other Realms on your
Kingdoms Net. These inbounds could be messages, gold or monster
transfer, Castle fortifications or a number of other Kingdom transit
data. It will search for files named KNET*.* and process them from your
inbound files directory as defined in KM.EXE. Please note that you
should NEVER edit this file. Information in it is check summed and very
strange things can happen to your inbound processing if the file data
does not correspond to the file and record checksums.

3.1.4. KNETOUT.EXE

KNetOut processes the file KTransit.Dat. KTransit is the file which
holds outbound information and data, some generated by Kingdoms itself,
most generated by InterBBS activities of the players on your BBS. Please
note that you should NEVER edit this file. Information in it is check
summed and very strange things can happen to your outbound Transit file
data does not correspond to the file and record checksums.

3.1.5. KMNT.EXE

KMNT is the Kingdoms Maintenance program. It should be run once daily. I
suggest you put it in your nightly maintenance. It updates the player
records, brings dead players back to life, packs the news files to
manageable lengths and does other assorted housekeeping. It is also the
means by which you can regularly poll other Kingdom nodes for net
statistic information. It will not, unless you specifically request it,
run more than once per day. Further information about KMNT is provided
in the Kingdoms Installation section.

3.2 Data Files


3.2.1. KIDX.DAT

Your distribution archive may or may not contain this file. KIDX.DAT is
the `Nodelist' for a Kingdoms network. Generally, the file should be
obtained from the Kingdoms coordinator for a Kingdoms net in which you
are to participate. As it is specific to a network of BBS's, it
generally won't be found in the archive. If your BBS is not listed in
this file, Kingdoms InterBBS functions will not operate.

3.2.2. KGAME.DAT

This file contains much of the static data used by Kingdoms such as
Armor, Weapons and Monster information. It MUST reside in your game
directory, as defined in the Manager and you should NEVER edit this
file. Records in it are checksummed and the game will not operate
properly (or not at all) if the file is tampered with.

3.2.3. KTEXT.DAT

This file contains much of the text data used by Kingdoms. It MUST
reside in your game directory, as defined in the Manager and you should
NEVER edit this file directly.

3.2.4. K*.KDI

Kingdoms uses the special type of display file, the ones with the .KDI
extension, for display. This is a more convenient and more efficient way
of managing display information that by using ANSI files within
Kingdoms. KDI files include things such as the opening screens, menus
for fast display in this format and news files for display within the
game. If you wish, you can also generate ANSI and ASCII versions of some
of these files during Maintenance so you can display them on your BBS
itself. See the section in this document on Maintenance Options. 3.3.
Generated Files

The following files will not be in the Kingdoms archive, but are created
and modified by Kingdoms as appropriate as people play the game. You
should never attempt to modify any of these files yourself as the game
will not function if checksums on the files do not match file data. ALL
.DAT FILES SHOULD BE BACKED UP ON A REGULAR BASIS.

3.3.1. KMSGHEAD.DAT & KMSGTXT.DAT

These are the Kingdoms message base files. They hold the Kingdoms
indexed message headers information and the associated message text
respectively.

3.3.2. KUSR.DAT

This is your Kingdoms Player file. It holds all information pertaining
to the users playing Kingdoms on your BBS.

3.3.3. KCFG.DAT

This file your Kingdoms Configuration file. There will only ever be one
of these per system (unless a Sysop is running multiple Kingdoms network
games on the one BBS) and it is maintained by KM.EXE. When Kingdoms
starts, it must start up in the SAME directory that this file resides
in.

3.3.4. KTRANSIT.DAT

This file holds information that is in transit (going to and from)
between Kingdom Realms. It is processed and maintained primarily by
KNETOUT and KNETIN. New data (eg, a Recon requested) is added to this
file by the Kingdoms Realms options in KINGDOM.EXE so it can be tossed
(exported) to the destination node by KNETOUT.

3.3.5. KSCORE?.KDI

These files are the scoreboard files for Kingdoms. There are KSCOREL.KDI
and a KSCORER.KDI files, which are the Local and Realm (InterBBS) score
files respectively. The Local score file is calculated dynamically while
the user is online and is therefore always up-to-date. The Realms score
file is generated by KMNT when it runs, using data from the current
Recon files to pick up the scores from remote Realms. For this reason,
it will only be as up-to-date as of a) when Maintenance was last run and
b) depending on the currency of existing recons. As mentioned
previously, KMNT can create ANSI and ASCII versions of these files
should you want/require them.

3.3.6. K?.LOG

Kingdoms produces several log files which should be obvious by name. All
logs, should you want to see any, are written to the Game directory, as
defined in the Manager. The logs generated include :

* KDOM.LOG - Kingdoms Player's log ... who's gone in and out of the game.
* KNET.LOG - Net processors logs, Knetout and Knetin update this.
* KERR.LOG - Any errors the game encounters are recorded here.
             Hopefully empty :-)
* KMNT.LOG - Maintenance log
* KCOORD.LOG - Only appears on the Coordinator node - see KCOORD.DOC.



Section 4 -Required Software/Kingdoms Environment

Kingdoms is designed to run under any Bulletin Board system that
supports the standard DORINFO1.DEF, DORINFOx.DEF and DOOR.SYS drop file
formats. Ezycom, Remote Access and Wildcat all support one or more of
these formats and doubtless many others do as well. If your BBS software
does not, several utilities are available on many boards to convert one
type of drop file (eg, DOORMASTER) to these standards. As discussed,
Kingdoms have InterBBS capability. To operate these functions you must
be a member of a network (which one, eg Fido, PodsNet, SigNet etc) does
not matter to Kingdoms, only that you have a three dimensional address
(points are not supported) and that you call someone (or they call you)
who also has any 3D address.

Kingdoms uses the .MSG format of mailer messages to manage its file
routing. Kingdoms will run with FrontDoor or another mailer program that
supports .MSG format netmail messages without difficulty. The
Blinkey/Squish mailer format is also supported through the /S parameter
on KNETOUT. If someone wants to send me a sample of another format, I'll
look at putting it into Kingdoms depending on demand. Kingdoms requires
a fossil communications driver to be resident in order to operate. It
does NOT have it's own internal comms routines as I don't see why
they're necessary, considering all BBS software I've seen requires a
Fossil driver resident anyway. It has been tested and works well with
both X00 by Ray Gwinn and BNU by David Nugent.

Kingdoms requires MS-DOS or an MS-DOS environment/window. At startup, it
will detect DOS, DesqView, Taskview, Windows and/or OS/2. According to
what it finds, it will automatically time slice away when Kingdoms is
idle to give more processor time to other tasks that might be busy.
Kingdoms has been tested on MS-DOS 3.3, MS-DOS 4.1, MS-DOS 5.0, MS-DOS
6.2 and DR-DOS 6.0. It has also been tested running under Desqview on a
stand alone PC, on a net server running Novell Netware Lite and on a
Client machine in a Netware Lite environment multi tasking with
DesqView. It works well under both Windows 3.1 and `95.

Kingdoms does not have a significant memory requirement (approx 400K
runtime memory), but it is recommended you swap your BBS out (using the
*M parm in EzyCom, RA and QBBS) before calling the game to give it as
much as possible and avoid possible memory shortages while running.
Kingdoms supports multi-line operation. That is, users may play Kingdoms
on more than one line concurrently. Up to and including 99 separate
lines (logged on players) active are supported at any one time.


Section 5 - Installation

5.1. Overview

Kingdoms can, in its simplest form, run as a local game on a single line
BBS. Likewise, it can run in a complex multi-line, networked
environment. Installation is, naturally enough, more time consuming for
the latter, but you will still find it pretty easy if you follow the
instructions below! Please DON'T think, if you've installed heaps of
games before, that you don't need to read this documentation. Frankly,
you'll probably miss something important if you don't at least read
through them first, OK? RTFM! For those who REALLY want to get moving,
and who won't listen to advice <g>, Appendix B of this document gives a
quick start procedure for getting the game up and running. The procedure
described in this section describes installation for a BBS setting up a
new game of Kingdoms. Instructions for upgrading Kingdoms from a
previous version are supplied in Appendix C : Upgrading Kingdoms.

5.2 Installation Step 1 - The Basics

Whatever environment you're installing Kingdoms in, you'll need to start
with these steps.

5.2.1. Unpack the Archive

Unpack the distribution archive into a directory the game will run from.
For this document, we assume Kingdoms is unpacked in C:\KINGDOMS.

5.2.2. Setting up your Configuration File

From C:\KINGDOMS, run KM.EXE, the Kingdoms Manager. This is where most
of your Kingdoms setup will take place. Modify the defaults provided to
whatever matches your system. At the bottom of your screen, a one line
description of the field you're on will be displayed. If you need more
information, please refer to the relevant section of the Kingdoms
Manager documentation, KM.DOC. DON"T choose the Network options in
KM.EXE yet. The next section covers that. Just set up the `Paths' and
`Other' sections in KM.EXE. If you are not part of a network, or you are
going to be the Coordinator for a Kingdoms network, leave the Self
Correction Frequency in `Other' set to zero.

If you're not participating in a Kingdoms network, you're finished this
part of the setup. All that remains is to set up your menu commands and
batch file to call Kingdoms from the BBS. If this is the case, press Esc
now and save the configuration you've set up at this point. Before you
head out, use the `Verify Paths' option to make sure the paths you've
entered are correct. If any are missing or incorrect, create them now
using the normal DOS MakeDir (MD) command or go back into Edit Paths to
correct any you mistyped. When done, exit the Manager by pressing Esc
and, if you're not in a Kingdoms network, skip straight to section 5.4,
Getting it Running, now. Multiline setup is addressed in this section
(5.4) also. If you are setting yourself up as part of a Network,
continue on to section 5.3, Network Configuration.



5.3 Installation Step 2 - Network Configuration

5.3.1. The KIDX.DAT File

To be a part of a network, you must have a valid Kingdoms KIDX.DAT file
in your Kingdoms directory. This file holds information on all the BBS's
in your Kingdoms net, including your own. The latest version should
always be available from your net coordinator.

Kingdoms won't let you into the Network/Routing configuration section,
and you cannot therefore define your network address as that's where you
define it, until it can find a KIDX.DAT file to use. 5.3.2. Network
Setup

5.3.2.1. Defining your Node.

Go into the Manager again and select the Network->Your Routing options.

If this is the first time you've used this option, ie, your network
address is not yet defined, a list of all the nodes in the Index will
pop up and you'll be asked to identify which node YOU are in the
nodelist. Using the up/down arrow keys, place the highlight bar over
your node and press enter. If your node is NOT listed, then press Esc to
get out of there and get an updated KIDX.DAT file from your Coordinator
that has you listed. Having identified your node on the Index, Kingdoms
will intelligently evaluate the network links contained in the Index
file itself and configure all your routing for you. There is nothing
more you need to do. If you wish, re- enter N>etwork Y>our Routing and
you can see what Kingdoms has done for you. Unless there is a major
problem, such as one of your links going down for an extended period or
offline alltogether, you should NEVER change the default routing
Kingdoms has set up for you. The links specified are based on
information supplied by your network Coordinator when s/he created the
Index originally and changing your local node could seriously disrupt
network traffic flow if you get it wrong. A far better course of action
if something like this does happen, is for you to contact your
Coordinator and inform him/her of the problem. The Coordinator can then
issue commands from his/her Realm to alter the links appropriately
network wide and bring everyone up-to-date with the new network flow. A
LOT of effort has been put into the network intelligence in Kingdoms and
I can say with a fair degree of confidence that it is considerably
smarter and considerably more robust than any other InterBBS game you
will have tried. Though the facilities are provided to change the
defaults if you need to therefore, please don't do so without consulting
your Coordinator! 5.3.2.2. Selecting Mail Flags & Type.

As above, there should rarely, if ever, be a need for you to modify your
routing definitions. You may, however, wish to activate (or deactivate)
various mail flags on nodes you directly communicate with. Outbound
packets can have their associated .MSG files set to HOLD (or not), to
CRASH (or not), or you may wish to use compression on mail going to
these nodes. These options can be configured using the Preferences
option in the Network menu. If you've been running a BBS for a while,
you probably already know what these things mean, but if not, a more
detailed explanation of each option is provided in section 3.2 -
Preferences - of the Manager documentation, KMANAGER.DOC.

5.4. Installation Step 3 - Getting it Running


At this point, you should have your configuration completed, including
any Network setup you require. This last step involves getting Kingdoms
up and running on your BBS, including setting it up to handle Multiline
operation.

5.4.1. Logging on Locally

Log yourself onto Kingdoms locally using "KINGDOM /L",  to check
everything is working as it should be. If not, make sure all the
directories you defined in KM.EXE exist. Misspelling directories are the
most common cause of problems in this area. For a local logon, Kingdoms
does not require a DORINFO or DOOR.SYS file. It will use the information
provided in the Manager to log you onto the game. When Kingdoms detects
a local logon, it will ask for a (real) name to logon as. This facility
is provided so you can logon as one of your players to help out if
problems occur. If you press Enter on the first name without entering
anything, you'll be logged on as the User name you defined as the Sysop
in the Kingdoms Manager.

5.4.2. Starting Kingdoms

Depending on your preference, you can run Kingdoms directly from your
BBS or by shelling to a batch file. 5.4.2.1. Using a Batch File

This is the recommended means of running Kingdoms. If you call
KINGDOM.EXE directly from a menu command, you'll have more to maintain.

Create a batch file that can be called from your BBS which changes to
C:\KINGDOMS, places  your door file into (if it is not already) the
directory you defined in KM.EXE, and executes KINGDOM.EXE. A sample
batch file is :

CD\KINGDOMS             ` Change to the Kingdoms directory
KINGDOM            ` Run Kingdoms
CD\EZY            ` Change back to the BBS directory
EXIT                    ` and go back to the BBS.

This is a very simple example of a batch file that will start a single
line Kingdoms game. If you're a multiline setup, the next section has a
sample setup for you to use.

5.4.2.2. Calling Kingdoms directly

If you prefer not to use batch files, then you can call KINGDOM.EXE
straight from your BBS but KCFG.DAT must exist in the directory you're
in when you shell out to Kingdoms in this case. If KINGDOM.EXE can't
find your configuration file when it loads, it will terminate with an
appropriate message.

5.4.2.3. Menu commands

A type 7 (Ezycom, RA, QBBS etc) menu command which will execute Kingdoms
will look like : C:\COMMAND.COM /C C:\KINGDOMS\KINGDOM.EXE *M

Create a menu command from a menu on your BBS to call the batch file
which starts Kingdoms. Alternatively you can execute Kingdoms straight
from the BBS command line, but keep in mind the configuration file must
be found as described in 5.4.2.2. Kingdoms operates fine from a type 7
(Ezycom/RA/QBBS) command, but you should specify the *M command line
switch (or equivalent) to swap the BBS out when Kingdoms runs to give it
plenty of breathing space.

5.4.3.  Maintenance, Network Tasks

5.4.3.1. Batch Commands

Add the Kingdoms maintenance program (KMNT.EXE) to your BBS nightly
maintenance. If you're in a net, also add the in and outbound mail
processors KNETIN and KNETOUT respectively to your BBS maintenance. If
adding all three (ie, you're in a net), then run them in the order KMNT,
KNETIN then KNETOUT. Your batch file commands for nightly maintenance
will, when you're in a Kingdoms Net, look like : ... REM : Kingdoms
Nightly Maintenance CD\KINGDOMS KMNT KNETIN KNETOUT REM : More
Maintenance Tasks ... ...

You should always run these utilities while in the main Kingdoms
directory where KCFG.DAT is located.

5.4.3.2. Maintenance Options - KMNT.EXE

KMNT will only run once per day and carries out numerous, essential
operations like reset user daily stats, resurrect dead characters, trim
the log and news files, pack the user and message bases, poll other
nodes for transit times, generate recon requests for nodes with outdated
recons.

Normally when KMNT runs, the messages about what it's doing fly by so
fast you don't get time to read them. If you wish to slow them down so
you can make sure it's working as it should, KMNT will accept the /Dn
(delay) command line parameter. Using this parameter will make Kingdoms
pause for `n' seconds after each section of the Maintenance completes.
For example, `KMNT /D10' will run KMNT and after all major operations,
KMNT will pause for 10 (ten) seconds. You can delay it for anything from
1 to 240 seconds between each operation. While paused, you can press a
key and it will immediately continue processing rather than waiting the
allotted time. The default is no delay between operations.

As already noted, KMNT should only run once per day. It will, in fact,
halt processing if this is attempted. It is possible however, that you
want to force it to run more than once. For example, you may want to
test or force a network poll. To accommodate this, KMNT will also accept
the /O parameter. If KMNT runs with /O provided, it will ignore the
once-per-day-run limit and process maintenance regardless. Running KMNT
with the override active will process options such as scoreboard
generation, message and user base file packing and network polls. It
will NOT process player options such as fights per day, healing etc that
occurs during a normal maintenance run. An abbreviated list of
parameters KMNT will accept can be displayed at any time by doing `KMNT
/?' at the command prompt.

KMNT also accepts the /S parameter. If this is present, KMNT will start
(several times a day if desired) and ONLY create the scoreboard files.
Once done it will terminate and no other processing (ie, no other
maintenance) will take place. This facility has been provided so it can
be run after the inbound and outbound processors finish to bring local
scoreboards up to date with, for example, incoming Recon information. /A
with /S will also produce ASC/ANS versions of these files.

You are now set up to run Kingdoms on a single line BBS, with or without
a Kingdoms network depending on what you've done so far. The following
section discusses the setup for Multi-Line BBS's and the additional
steps you need to take to get it running in these environments.

5.5. Installation Step 4 - Multiline Configuration

Kingdoms fully supports multiple line, concurrent users. In this
environment a user may also display from within Kingdoms who else is in
Kingdoms and, generally, what they're doing. Through the Courier Guild,
players may also chat one-on-one in real time while in the game.

Kingdoms will accept the `/Nn' parameter at startup. Should it be
present, Kingdoms will operate as node `n'. A maximum of 99 concurrent
nodes are supported. For example, `KINGDOM /N3' will start Kingdoms with
the player playing on node 3. If /Nn is not present, Kingdoms will
assume single line (Node 1) operation. Kingdoms uses the same
configuration file for multiline operation as it does for single line.
Unlike a LOT of doors there is no need to create a config file in the
Manager for each line Kingdoms will run on. Obviously however, you need
to tell Kingdoms where it can find the drop file (DORINFO?.DEF or
DOOR.SYS) for each line. This is done by use of the /D parameter when
you load KINGDOM.EXE rather than having to create and look after
numerous configuration files. Using /D simply overrides the BBS path you
defined in the Manager, allowing Kingdoms to pick up the drop file from
a separate place for each line that's running. The /D parameter is
followed by the path and file name of the appropriate drop file. Usually
the /Nn parameter just discussed will accompany the /D parameter. For
example, if you start Kingdoms with ...

   KINGDOM /N2 /Dc:\ezy\line2\dorinfo1.def

   ... then the DORINFO1.DEF file in \ezy\line2 will be used for this
session rather than whatever is specified in the Kingdoms configuration
file. If /D\path\filename is not present, it will default to using a
DORINFO1.DEF file in the path specified in the Manager. Should the /D
parm be used without the /N parm, a warning will be issued to the Sysop
when Kingdoms starts, but it will honor the /D override and keep
operating, assuming that Kingdoms is running node 1. The same procedure
applies if you're using DOOR.SYS - just use that with the /D parameter
instead of DORINFO?.DEF. Please note you do NOT need to tell the Manager
what type of drop file you're using as you do in many other BBS games.
Once again, Kingdoms is that bit smarter and will work it out for itself
based on the name of the dropfile supplied. :-) Assuming you're using a
batch file to run Kingdoms, your commands to run Kingdoms will look
something like ...

MENU Command : c:\command.com /c c:\batch\kingdom.bat *N *M

The *M under Ezycom and similar packages will swap the BBS out of memory
while the game runs. This is highly recommended! The *N will pass the
current node number to the batch file as variable 1 (Check your DOS
manual) which is very simple ...

    KINGDOM.BAT
    -----------
    CD\KINGDOMS
    KINGDOM /N%1 /DC:\RA\LINE%1\DORINFO%1.DEF
    CD\RA\LINE%1
    EXIT
    -----------

Neither the order nor the case of parameters provided, as with all
Kingdoms parameters, is significant. Parameters must be separated by at
least one space. Data associated to a parameter, eg the /D and the
C:\... above, must immediately follow each other, no spaces between.
Depending on your BBS software, you don't always need the 3rd line to
return you to the BBS directory after someone exits Kingdoms. You also
don't generally need the EXIT anymore either, but it doesn't hurt to
have both there. That's it! For whatever your system setup, you are now
ready to play the latest and best Inter-BBS game around!

Enjoy!

Section 6 - Maintenance Options

In addition to the Maintenance functions described above in the
installation procedures, KMNT can do a few other things. Runtime
paramaters that KMNT will accept include :

6.1. Game Reset

KMNT will accept the /RESET parameter (KMNT /RESET). Rather than
performing normal maintenance functions, this will force a complete game
reset, removing all players and resetting all data files. You are given
some chances to back out of this should you not be sure, as a reset
cannot be reversed, except by restoring all data files to their state
before the reset was issued.

6.2. Override Reset

If you're in a network game, you are probably aware that the Network
Coordinator can issue a network wide reset command, which will
automatically reset all nodes in the network. There MAY be a reason you
do not want to be included in this, in which case you can force
Maintenance to ignore the Coordinator Reset instruction by adding the
/NORESET parameter to Maintenance when it runs. Note if you do this
however, that a few things :

* A message will be sent to your Network Coordinator informing him/her
of your override. If you don't have a good reason for doing it (and it
should have been agreed with the Coordinator in the first place for you
to do so), the Coordinator has the ability to simply remove your node
from the network until you do so, or to physically delete your node if
he/she is annoyed enough. In short, don't use this unless the
Coordinator is aware you're going to, and he/she agrees.

* The Reset will NOT be cancelled, just overridden for that run. Unless
the Coordinator issues a directive to the network to cancel any pending
resets (which he/she can do), then Maintenance will continue
indefinately to try to honor the reset request. You would have to leave
your /NORESET in place permanently if you don't want your node getting
reset.

6.3. Delay Processing

Maintenance performs it's tasks in blocks, informing you on screen of
progress. Often the status information flies by quickly however, and you
don't get a chance to read it. If you want to slow it down a little, you
can add the /Dxx parameter to KMNT when it runs. Doing this will make
KMNT pause for xx (1 to 240) seconds between processing each block (eg,
user maintenance, then news file packing, then scoreboard generation,
etc) so you have time to read what's on the screen. In my nightly
maintenance I have /D5 in place permanently so if I happen to be around
at 3am when it runs, I can see what's going on. It means maintenance
takes about 30 seconds extra to run (there being 6 logical processing
blocks to a run) but for the few times I want to see it, who cares about
the extra few seconds taken the rest of the time at 3am? :-)

If you do happen to be watching it and want it to not wait for the full
duration of a Delay, just hit a key and the next block will be processed
immediately.


6.4. Same-Day Run Override

Normally, Maintenance will only run once a day. If you attempt to run it
more than once, it will terminate immediately with a message to that
effect. Should you need to for some reason, you can run Maintenance with
the /O parameter, which will override this and continue processing
normally for that day.

6.5. Create ACS/ANS Files

The News and Scoreboard files created and displayed within the game are
.KDI files, which is a special file format created for the game to speed
up processing and, in particular, reduce the overhead involved with
interpreting and displaying ANSI files in color on the local screen when
a player views them. This is all very nice, but it means these files
can't be displayed outside the game, such as on a BBS menu as you may
wish to do. If you run KMNT with the /A parameter, an extra processing
block will be enabled which will create ASC and ANS versions of your
existing news (Knewst & Knewsy) and scoreboard (kscore?) files. The
files will be created in the directories you have defined as your ASC
and ANS paths in the Manager.

6.6. Create Scoreboards

Running KMNT with the /S parameter will invoke ONLY the processing to
create the .KDI scoreboard (local and remote) files. NO other
maintenance processing will take place if you run KMNT with this option
and, unlike a normal maintenance run, KMNT can be run with /S as many
times a day as desired. This option is available to allow the Sysop (if
desired) to do a `scoreboard run' of KMNT after inbound and/or outbound
processing. This will bring the remote scoreboards up-to-date after any
score changes that may have resulted from inbound or outbound traffic
processing. The /A paramater may also be used in conjunction with the /S
parameter. No other parameters will be recognised or processed if /S is
provided. Using /A as well will also generate .ASC and .ANS versions of
the new score files if desired.


Section 7 - Registration


When you register, you will receive a registration number that will
remove the `Level 10' restriction in Kingdoms. Kingdoms is not crippled
in any way except to, in unregistered versions, restrict a player from
gaining a level greater than level 10.

See the accompanying file KREG.DOC (or the text version, KREG.TXT)  for
more information on Registration. Section 8 - Contact Information


You can contact me and/or pick up the latest version of Kingdoms by the
following means :

THE WEB BBS

   Line 1 : 61-2-9528-5941 - 33600, 24hrs Mail, FREQ `KINGDOMS'
   Line 2 : 61-2-9528-2235 - 28800
   Line 3 : 61-2-9528-4250 - 14400

   Kingdoms is a `Free File' download if logged onto the Web directly.

BETA & REGISTRATION SITES

KINGDOMS is available for FREQ at the following sites :

Way Out West, Willmont, NSW, Australia        69:1171/3 (Battlenet)
Restless (NRFTW) BBS, Glossodia, NSW, Australia    69:1171/313 (Battlenet)
The RUNWAY BBS, Stanmore, NSW, Austraia        3:712/506 (Fidonet)
The Dead Zone, Cincinnati, Ohio, USA            1:108/430 (Fidonet)
Wizard's Inc BBS, Victoria, BC, Canada.        1:340/21 (FidoNet)
Swivel's BBS, Flaxmere, Hawkes Bay, NZ.        3:776/305 (FidoNet)


INTERNET

The latest version of Kingdoms, Online Registration forms and info and
more can be found on the Kingdoms home page on the Net at
http://www1.tpgi.com.au/users/kingdoms. This is the primary support
page/site for Kingdoms worldwide.

I can also be contacted at [e-mail].


Section 9 - FAQ

This section of the documentation will be updated with new releases to
include any Frequently Asked Questions that come up regularly from
Sysops.

9.1. Where do I specify my locked port?

   You don't. Kingdoms requires a fossil driver which you should have
   already defined as locked if you want it that way. It uses that quite
   happily without further specification/definition.

9.2. Kingdoms thinks someone is online when there isn't.

   In the Manager, File menu, select the `User on Flag' option. This
   will scan your user file and turn off any `online' flags which are
   `on'.

9.3. Kingdoms thinks Maintenance is running when it isn't.

   In the Manager, File menu, select the `Maint Flag' option. This will
   turn off the flag that indicates to Kingdoms that maintenance is
   running.

9.4. I have an Index file, but the Manager is telling me I don't!

   When you get an Index file from your Coordinator, it is probably
   called KIDX.nn, where `nn' is the Network ID for your Kingdoms game.
   You need to rename it KIDX.DAT, and it needs to be in your Game
   directory (as defined in the Manager) for Kingdoms to find it. While
   you're there, make sure also that your NetId in the F>ile, O>ther
   section of the Manager is set to the correct NetId!

9.5. Realms on my Index are numbered differently to my uplink!

   This doesn't matter! Kingdoms ALWAYS does Index searches based on
   actual address information contained in the Index. It never searches
   by physical Index record number. Thus, you can have nodes 1:2/3,
   2:3/4 and 3:4/5 numbered (physically as they appear in an Index Dump)
   as records 1, 2 a 3 while other nodes can have them numbered 3, 2 and
   1 physically and it will make no difference whatsoever to Kingdoms.

9.6. I want to be able to generate Scoreboards anytime!

   You can! See sections 6.5 and 6.6 in this document regarding the /A
   and /S switch for KMNT.

Appendix A : Error Codes

The following codes are some of those you may get reported in KERR.LOG.
The ones provided are those you can generally do something about. If you
get an error that isn't covered here, please contact the Author
immediately with ALL POSSIBLE DETAIL of the problem including, of
course, the KERR.LOG message!

Error - Description
     Explanation/Possible Solutions
---  -------------------------------------------------------------
7 -  Out of memory
     Are you using *M to swap the BBS out before running Kingdoms?
     Give it more memory in which to run.
24 - Device Timeout
     An I/O device (probably your COM port) is not responding.
25 - Device Fault
     A device has returned a hardware fault condition.
27 - Out Of Paper
     I hope you never get this, cos Kingdoms isn't supposed to print
     anything :-)
53 - File Not Found
     Do you have your paths defined correctly? Do you have your .KDI
     files from the distribution archive in the Game directory defined
     in the Manager? Can Kingdoms find DORINFO#.DEF or DOOR.SYS? Are you
     in the Kingdoms directory when you try to execute Kingdoms? Have
     you renamed or deleted anything accidentally?
57 - Device I/O error
     Possible interrupt conflict on your system or hardware error.
61 - Disk Full
     I hope you notice this BEFORE Kingdoms picks it up! :)
64 - Bad File Name
     Possible Kingdoms error, but check the options in error 53 before
     reporting!
67 - Too many files
     Kingdoms has tried to open or save a file and the DOS 255 file-
     directory maximum has been exceeded. Clean up your hard drive ...
70 - Permission Denied
     Your drive is write protected or a file is locked that Kingdoms is
     trying to access. Rebooting will often fix the latter as this may
     happen if network software becomes unstable. Please report it if
     you can't solve it or if it persists as it may be a Kingdoms
     problem. If you're running a multitasker, check your other tasks!
72 - Disk Media error
     Drive hardware has detected a physical error on your disk media.
     Take a backup immediately - something bad's goin' down ...
75/76 - Path/File access errors
     Possible Kingdoms error, but check the options in error 53 before
     reporting!




Appendix B : QuickStart Installation

I suggest you read Section 5, the Installation documentation in full
before you install the game, but for those feeling brave, here's a
quickstart setup!

* Unpack the archive into a separate directory.

* If you're in a Kingdoms network, get an Index file (KIDX.nn, where nn
is your NetId) off your Network Coordinator. Place it in your game
directory and rename it KIDX.DAT.

* Run KM, the Kingdoms Manager. Define your Paths and Other information
under the File menu. Make sure your NetId is correct if you're playing
in a Network, othewise leave it blank.

* If you're in a network, go into Network>Your Routing and select your
node on the Index to let Kingdoms know who you are. It will
automatically configure the correct routing definitions for all other
nodes in your network.

* Run Kingdoms locally to check all is well using KINGDOM /L

* Set up a batch file to call Kingdoms from your BBS. Swap the BBS out
of memory (normally using *M) when you call Kingdoms.

* If you're running multiline, start Kingdoms with two parameters. 1 ...
/Nx, where x is the node number and 2 ... /Ddrive:path/dorfile, where
drive:path/dorfile is the full path and filename to your dorinfo?.def or
door.sys file for the respective node.

* Add KMNT, the Kingdoms maintenance program, to your nightly batch
file. If you're in a network, add KNETIN and KNETOUT also. Run them in
the order KNETIN, KMNT, then KNETOUT.

* That's it! If you have any problems, read the documentation fully!



Appendix C : Upgrading from Prior Releases


Kingdoms 2.21 is the first public release of Kingdoms after version
2.20. You must install Kingdoms 2.21 as a new installation, or upgrade
from version 2.20 using the `220to221.exe' utility supplied in the
distribution archive. You cannot upgrade to Kingdoms 2.21 from any
release prior to 2.20.

To upgrade from Kingdoms 2.19 or a prior release :

You must first install version 2.20 of Kingdoms. The 220to221 utility
supplied with the distribution archive will not convert a prior version
of Kingdoms properly.

To upgrade from Kingdoms 2.20 to version 2.21 :

1. Backup your existing game data files (*.dat)
2. Unpack the distribution archive to your Kingdoms game directory.
3. Run the upgrade utility, 220to221.exe. If you use this utility, your
   Kingdoms game does NOT require a reset to play 2.21.
4. Run the Manager and confirm all is well before playing.



                     - End of Sysop Documentation -